Project M.A.T.S.O. - Masterly Advanced Technicaly Supreme Overhaul (SVI 4.1.7)

This is technical readme for the ENB effects modders resources by Matso, Project M.A.T.S.O.

1. List of effects

 M.A.T.S.O. effects are placed in three files - enbeffect.fx, enbbloom.fx and enbeffectprepass.fx. The main of them are as follows:

	- enhanced bloom (BLM, in enbbloom.fx file),
	- anamorphic lens flare (ALF, both in enbbloom.fx and enbeffectprepass.fx files),
	- letterbox effect (LTB, in enbeffect.fx file),
	- depth of field (DoF, in enbeffectprepass.fx file),
	- chromatic aberration (ChA, in enbeffectprepass.fx file),
	- prior DoF effects (PRE, in enbeffectprepass.fx file),
	- post Dof effects (POST, in enbeffectprepass.fx file)
	
 Each of the effects has a list of features/subeffects. A feature is a user-customizable variable/option/flag, which value/state can be altered
or disabled. Options and flags are prefixed with either 'USE_' or 'ENABLE_'. Variables are in 'camel case' (fBaseBlurRadius). There are also
constants and macros (both in either upper or lower case - linear(t), DOF(s,f), PI), which values/formulas should not be changed. Some are written
in 'snake case' (with use of underscores - BOKEH_VIBRANT).
 Subeffects are complex features of a certain effect. Users can add their own subeffects in selected files and order with existing effects. They
refer to mixing two effects (DoF plus ChA - ChAnDoF - chromatic aberration samplind in DoF) or application of some of them prior or post the main one
(sharpening effect, image grain effect).
	
2. Effects' features

2.1. Enhanced bloom (BLM)

 BLM is enabled by setting 'EnableBloom' to true in enbseries.ini file. Within the enbbloom.fx file user can disable/enable tinting option (USE_TINTING)
and change it's value to either 1 (fixed color tint, default) or 2 (texture sample tint). Also there are constants, changeable by the user:

	- TINT_COLOR - fixed color tint, used should the USE_TINTING be set to 1, default option,
	- TINT_TEXTURE - texture sample tint, used should the USE_TINTING be set to 2,
	- TINT_LEVEL - a blend factor for the tinting, the bigger the more visable tinting becomes.

Additionally there are three variables used for scaling the per-pixel area that takes part in definition of BLM (BloomRadius0, BloomRadius1, BloomRadius2).
Changing their values to bigger ones can make the whole screen be slightly tinted, depending on the overall brightness of the visable image on the screen.

2.2. Anamorphic lens flare (ALF)

 ALF is provided either with BLM or in enbeffectprepass.fx file. Thus, to enable it, BLM need to be enabled (preferably). To enable it in the second
option, enable DoF. There is also a flag in enbbloom.fx file (USE_ANAMFLARE) that allows to disable/enable the effect while still using BLM itself.
ALF uses three variables to govern it's behaviour:

	- fFlareLuminance - brightness level above witch ALF will be applied,
	- fFlareBlur - the ALF size, how much the bright enough points on the screen will be stretched,
	- fFlareIntensity - blend factor for the effect, the bigger the more visable ALF becomes.
 
There are two additional variables not present in enbeffectprepass.fx ALF version (fFlareAxis and fFlareTint). They allow to change blur axis and color
of the effect, in the order given.
 
2.3. Letterbox effect (LTB)

 LTB is present within the enbeffect.fx file. Thus, to enable it uncomment the flag USE_LETTERBOX_EFFECT in the file. The effect uses single variable
(fLetterboxOffset) to govern the amount of the screen to be set to black color. It is percentage of the screen. Set to 0 means no black bars, while set
to 50, covers all screen with them - pure darkness.

2.4. Depth of field (DoF)

 To enable DoF set EnableDepthOfField to true in enbseries.ini file and enable flag ENABLE_DOF in enbeffectprepass.fx. While using DoF, ENABLE_CHROMA
flag should be disabled.

2.4.1. DoF variations

 There is a set of DoF variations available. Each of them is defined a separate shader. See sections below for more details.
 
2.4.1.1. Complex 1.0 DoF

 To use Complex 1.0 DoF variation set PS_ProcessPass_DepthOfField to DepthOfField_Complex_1_0 (or uncomment relevent line in enbeffectprepass.fx file).
Remember to comment any other PS_ProcessPass_DepthOfField deffinitions to prevent errors. Basicly this variation is controlled by the following set of
variables:

	- fFocusBias - bigger values for nearsightedness, smaller for farsightedness (lens focal point distance),
	- fDofCutoff - manages the smoothness of the DoF (bigger value results in wider depth of field),
	- fDofBias - distance not taken into account in DoF (all closer then the distance is in focus),
	- fBlurScale - governs image blur scale (the bigger value, the stronger blur),
	- fBlurCutoff - bluring tolerance depending on the pixel and sample depth (smaller causes objects edges to be preserved).
	
Additinally there is a set of macros available for diffrent definition of DoF out-of-focus amount calculator. To switch between them change the macro
DOF to linear version (DOF1), quadratic version (DOF2) or cubic version (DOF3, default option). Note that these options only work for non-manual DoF.
 
2.4.1.2. Complex 1.1 DoF

 To use Complex 1.1 DoF variation set PS_ProcessPass_DepthOfField to DepthOfField_Complex_1_1 (or uncomment relevent line in enbeffectprepass.fx file).
Remember to comment any other PS_ProcessPass_DepthOfField deffinitions to prevent errors. Basicly this variation is controlled by the following set of
variables:

	- fRetinaFocusPoint - retina focus point (little less the fRelaxedFocusPower causes myopia/nearsightedness),
	- fRelaxedFocusPower - eye relaxed focus power (change it along with fRetinaFocusPoint to alter the depth of field),
	- fAccomodation - accomodation (little above fRetinaFocusPoint + fAccomodation leads to hyperopia/farsightedness),
	- fBaseBlurRadius - base blur radius (higher values mean more blur when out of depth of field),
	- fRadius - maximum blur radius in pixels (size of the blur shape).
	
The variation is based on OBGE Depth of field shaders, by Tomerk.

2.4.1.3. OBGE-like DoF

 To use OBGE-like DoF variation set PS_ProcessPass_DepthOfField to DepthOfField_OBGE (or uncomment relevent line in enbeffectprepass.fx file).
Remember to comment any other PS_ProcessPass_DepthOfField deffinitions to prevent errors. Basicly this variation is controlled by the same set of 
variables as in Complex 1.1 DoF variation. See relevent section for more details.

2.4.1.4. False DoF

 To use False DoF variation set PS_ProcessPass_DepthOfField to DepthOfField_False (or uncomment relevent line in enbeffectprepass.fx file).
Remember to comment any other PS_ProcessPass_DepthOfField deffinitions to prevent errors. Basicly this variation is controlled by the same set of 
variables as in Complex 1.1 DoF variation. See relevent section for more details. Performance can be slightly increased here by enabling option
USE_SINGLE_PASS, though experience can be diffrent then in case of this option disabled.
 
2.4.2. Smooth DoF

 Smooth DoF actually refers to two things - smooth blur and smooth focus transition. First of them is an alternative for bokeh DoF. To enable it
disable USE_BOKEH_DOF option. All smooth control variables depends on used DoF variation. See relevent section for more details.
 As far as the second meaning of 'smooth DoF' is concerned, to enable it uncomment USE_SMOOTH_DOF option. In some cases this option can lead to DoF
crash, while playing on some non-Nvidia cards (?). Should it be present, disable the option.
 
2.4.3. Bokeh DoF

2.4.3.1. Bokeh parameters & modifies options

 To enable bokeh DoF uncomment USE_BOKEH_DOF option. This feature is much complex and is governed by following parameters:
 
	- fBokehCurve - the larger the value, the more visible the bokeh effect is (not used with brightness limiting),
	- fBokehIntensity - governs bokeh brightness (not used with brightness limiting),
	- fBokehConstant - constant value of the bokeh weighting,
	- fBokehMaxLevel - bokeh max brightness level (scale factor for bokeh samples),
	- fBokehMin - minimal input cutoff (anything below is 0),
	- fBokehMax - maximal input cutoff (anything above is 1),
	- fBokehMaxWeight - any weight above will be clamped.
	
Note that not all of the above parameters are always in use. It depends on what modifiers options are used. The modifiers additionally change the way
bokeh weight is calculated. USE_BRIGHTNESS_LIMITING, USE_WEIGHT_CLAMP and USE_ENHANCED_BOKEH are bokeh modifiers options. First two are a way to limit
brightness of outcome image. First of them scales basic weight to certain level (controled by fBokehMaxLevel, fBokehMin, and fBokehMax). The second 
clamps any weights that are over the value of fBokehMaxWeight. USE_ENHANCED_BOKEH option causes bokeh to be more pronounced and enhanced.
 
2.4.3.2. Bokeh formulas

 Beyond bokeh parameters and modifiers options, there are several bokeh formulas available too. To switch between them set macro BOKEH_FORMULA to one
of the following - BOKEH_VIBRANT, BOKEH_RADIANT or BOKEH_PASTEL.
 
2.4.3.3. Bokeh shapes

 Additinally there is available a set of bokeh shapes - natural, organic, imitating bokeh for human eye (USE_NATURAL_BOKEH), octagonal (USE_OCTAGONAL_BOKEH)
and hexagonal (USE_HEXAGONAL_BOKEH). The last two work only when natural shape is disabled. There always need to be one of them enabled to prevent errors.

2.4.4. Manual DoF

 To enable manual version of DoF, uncomment USE_MANUAL_FOCUS option. Manual DoF applies to all DoF variations, though experiance can alter, depending
on which of them is actually used. Manual DoF refers to manual focus and aperture. It allows to change the depth of field parameters using key combination
'PageUp/PageDown' plus keys '1' and '2'. First conbination (with key '1') alters focus distance. To define a appropriate focus distance base, alter value
of the variable fFocusDistance (1.0 by default). Second combination manually changes depth of field (aperture size). In case of Complex 1.0 DoF variation
this combination alters value of fDofBias variable. Along with it there are two additional combinations (with keys '3' and '4', Complex 1.0 only), allowing
to manually change value of fDofCutoff ('3' plus 'PageUp/PageDown') and amount of blur applied to the image ('4' plus 'PageUp/PageDown'). The last combination
is available only when USE_MANUAL_BLUR_SCALE option is enabled. Manual DoF allows also to switch between smooth and bokeh DoF. The feature is controled
by additional key combination ('PageUp/PageDown' plus '7'), while USE_SWITCHABLE_MODE option is enabled. Note that 'PageUp' increases a relevent 
variable value, while 'PageDown' decreases it. It is recomended to use Complex 1.1 manual DoF for any cinematic (video making) applications.
 
2.5. Chromatic aberration (ChA)

 ChA is an effect applied instead of DoF. To apply it with DoF see section 3.4. The non-DoF version is enabled by flag ENABLE_CHROMA. At the same time
ENABLE_DOF flag should be disabled. Both ChA and ChAnDoF use the same set of variables:

	- fvChroma - vector of ChA channels (RGB) scale values, controls ChA shift for red, green and blue values of the pixel color separately,
	- fBaseRadius - defines area of the image least influanced by the effect (in reference to the screen center),
	- fFalloffRadius - defines how swift is the transition between the least and the most influanced area of the image, need to bigger then the above,
	- fChromaPower - overall power of the effect, the bigger the more pronounced the effect becomes.
 
2.6. Prior DoF effects (PRE)

 PRE is a set of subeffects applied before DoF. Enable them with flag ENABLE_PREPASS in enbeffectprepass.fx file. In current version of the file there
are two subeffects available (applied in the order given) - image sharpening (ISHP) and ALF. For more details see section 3. and its relevent subsections.
Within the PRE user-defined effects are possible to be applied. See section 4. for more details.
 
2.7. Post DoF effect (POST)

 POST is a set of subeffects applied after DoF. Enable them with flag ENABLE_POSTPASS in enbeffectprepass.fx file. In current version of the file there
is one subeffect available - image grain (IGRN). For more details see section 3. and its relevent subsections. Within the PRE user-defined effects are
possible to be applied. See section 4. for more details.

3. Subeffects

3.1. Image sharpening (ISHP)

 ISHP is enabled by USE_SHARPENING option, with ENABLE_PREPASS flag enabled too. Basicly the subeffect is controled by two variables - fSharpScale and
fvTexelSize. First of them governs the intensity of the effect (bigger values cause more sharpening). The second one should be set to reciprocal of the
screen resolution (given 1920x1080 one should set (1/1920, 1/1080) or (0.000520833, 0.000925925)). Note that the texel size is used in other effects too.
 
3.2. Image grain (IGRN)

 IGRN is enabled by USE_IMAGEGRAIN option, with ENABLE_POSTPASS flag enabled too. There are two variables to control the subeffect. First is fGrainFreq,
that referes to the frequency of the image grain, in other words how big the grains are. Last of the two (fGrainScale) governs how much the subeffect
is visible (increase the value to get really graind image). There is also SEED constant. It is used for grain randomness. It can be set to 'Timer.w'
(by default) to achieve film grain, or to 1, causing the grain to static (not changing in time).
 
3.3. Anamorphic lens flare (ALF)

 ALF in enbeffectprepass.fx is enabled with USE_ANAMFLARE and ENABLE_PREPASS flags. See section 2.2. for details. Note that the outcome of the ALF
used in enbeffectprepass.fx can differ from the one associated with BLM.

3.4. Chromatic aberration sampling in DoF (ChAnDoF)

 ChAnDoF is enabled by USE_CHROMA_DOF option. See section 2.5. for more detail.
 
4. User-defined effects (for advanced user only)

 Both PRE and POST are capable with application of user-defined subeffects. Note that definition of such effects requires HLSL shading skills. To add
an effect to either PRE or POST create a shader and add it to one of the passes. The user-defined shader can look likewise:

float4 PS_ProcessPass_UserDefinedSubEffect(VS_OUTPUT_POST IN, float2 vPos : VPOS) : COLOR0
{
	float4 res = 0.0;
	// effect code here
	return res;
}

Note that there is a 'PS_ProcessPass_None' shader provided with the code that can be a helpfull base (pass through effect). Note also that any user-defined
subeffect should be applied after any existing, embedded subeffects (ISHP, IGRN, ALF) to prevent errors. The PRE and POST are FX techniques. When adding
new subeffects they are applied within one of them, thus worinking on the output of the previous technique (in case of POST the output is 'DoF-ed' image).
Usage of a number of subeffects within a single pass requires application of blending. Output of one subeffect is not visible to another, subsequent one,
e.g. ALF doesn't see changes made by ISHP. Thus not all kind of effects are here available. Note eventually that adding sophisticated subeffects can lead
to performance losses.

5. Archives & Miscellaneous

 With the Project M.A.T.S.O. there is a set of older, archival effect files available. Each of the files is placed in version relevent subdirectory. One
can use it instead of the current version, but the overall effect can differ in such a case. There is also a set of predefined settings using simpler,
more performace optimised code version. All options provided with the mod are placed within subdirectories with relevent names.

6. Future development

 Below is list of effects/subeffects/features of the Project M.A.T.S.O. considered for future development:

	- Level-of-detail (LoD) based DoF (LoDDoF),
	- HDR dependent bokeh (HDRB),
	- Separate day/night/interrior/exterior HDR settings (SpHDR),
	- Adaptive Sunglare (AS),
	- Advanced Light Lens Distortions (ALLD).

7. Credits

 Boris Vorontsov, for the ENB Series,
 Tomerk, for OBGE Depth of field shaders,
 HeliosDoubleSix, for the great HDR setting and additions to the effects,
 Kyokushinoyama, for essential and everlasting support, and big help in making Project M.A.T.S.O. even come to live,
 solsikke737 and Staind716, for beta-testing and fantastic screenshots.
 
 Bless You,
 MK
 